با JavaScript Temporal API برای مدیریت مدرن تاریخ و زمان آشنا شوید. یاد بگیرید چگونه اشیاء Date قدیمی را با یک API قدرتمند، شهودی و آگاه از منطقه زمانی جایگزین کنید.
JavaScript Temporal API: دستکاری مدرن تاریخ و زمان
شیء Date جاوا اسکریپت مدت هاست که منبع ناامیدی برای توسعه دهندگان بوده است. تغییرپذیری، عدم پشتیبانی داخلی از منطقه زمانی و API نامناسب آن منجر به کتابخانه ها و راه حل های بی شماری شده است. خوشبختانه، Temporal API با هدف رفع این کاستی ها، یک راه حل مدرن، شهودی و آگاه از منطقه زمانی برای دستکاری تاریخ و زمان در جاوا اسکریپت ارائه می دهد.
Temporal API چیست؟
Temporal API یک شیء سراسری جدید، Temporal است که یک روش مدرن و استاندارد برای کار با تاریخ ها و زمان ها در جاوا اسکریپت فراهم می کند. این API برای جایگزینی شیء Date قدیمی طراحی شده است و بهبودهای قابل توجهی از نظر طراحی API، تغییرناپذیری، پشتیبانی از منطقه زمانی و قابلیت استفاده کلی ارائه می دهد. این API بخشی از پیشنهاد ECMAScript است و در موتورهای اصلی جاوا اسکریپت در حال پیاده سازی است.
مزایای کلیدی Temporal API:
- تغییرناپذیری: اشیاء Temporal تغییرناپذیر هستند، به این معنی که عملیات روی آنها اشیاء جدیدی را برمی گرداند به جای اینکه شیء اصلی را تغییر دهد. این به جلوگیری از عوارض جانبی غیرمنتظره کمک می کند و درک کد را آسان تر می کند.
- API واضح: این API به گونه ای طراحی شده است که شهودی تر و سازگارتر از شیء
Dateقدیمی باشد. - پشتیبانی از منطقه زمانی: Temporal پشتیبانی قوی از مناطق زمانی ارائه می دهد و به شما امکان می دهد با تاریخ ها و زمان ها در مکان های مختلف در سراسر جهان کار کنید.
- پشتیبانی از تقویم: فراتر از تقویم میلادی، API اجازه می دهد تا از سیستم های تقویم دیگر نیز استفاده شود و برنامه های کاربردی جهانی را تسهیل می کند.
- مدیریت ثانیه های کبیسه: Temporal API ثانیه های کبیسه را در نظر می گیرد و محاسبات دقیق تری از زمان ارائه می دهد.
شروع کار با Temporal
در حالی که Temporal API هنوز در حال توسعه است و هنوز به طور کامل در همه مرورگرها و محیط های Node.js پشتیبانی نمی شود، می توانید از یک polyfill برای شروع آزمایش با آن استفاده کنید. می توانید polyfill را از طریق npm نصب کنید:
npm install @js-temporal/polyfill
سپس، polyfill را در کد جاوا اسکریپت خود وارد کنید:
import { Temporal } from '@js-temporal/polyfill';
پس از نصب polyfill، می توانید شروع به استفاده از شیء Temporal و کلاس های مختلف آن کنید.
کلاس های اصلی Temporal
Temporal API چندین کلاس کلیدی برای کار با تاریخ ها و زمان ها ارائه می دهد:
Temporal.PlainDate: نشان دهنده یک تاریخ تقویمی (سال، ماه و روز) بدون هیچ گونه اطلاعات منطقه زمانی یا زمان روز است.Temporal.PlainTime: نشان دهنده زمان روز (ساعت، دقیقه، ثانیه و کسری از ثانیه) بدون هیچ گونه اطلاعات تاریخ یا منطقه زمانی است.Temporal.PlainDateTime: نشان دهنده تاریخ و زمان بدون هیچ گونه اطلاعات منطقه زمانی است.Temporal.ZonedDateTime: نشان دهنده تاریخ و زمان با یک منطقه زمانی خاص است.Temporal.Instant: نشان دهنده یک نقطه خاص در زمان است که بر حسب نانوثانیه از زمان epoch یونیکس اندازه گیری می شود (1 ژانویه 1970، ساعت 00:00:00 زمان هماهنگ جهانی (UTC)).Temporal.TimeZone: نشان دهنده یک منطقه زمانی است.Temporal.Duration: نشان دهنده یک مدت زمان است، مانند ساعت، دقیقه یا ثانیه.Temporal.Now: دسترسی به تاریخ و زمان فعلی را فراهم می کند.
کار با PlainDate
کلاس Temporal.PlainDate نشان دهنده یک تاریخ بدون هیچ گونه اطلاعات منطقه زمانی یا زمان روز است. برای نشان دادن تولدها، سالگردها یا سایر رویدادهای مبتنی بر تاریخ مفید است.
ایجاد یک PlainDate:
const plainDate = Temporal.PlainDate.from({ year: 2024, month: 10, day: 26 });
console.log(plainDate.toString()); // Output: 2024-10-26
همچنین می توانید یک PlainDate از یک رشته در قالب ISO 8601 ایجاد کنید:
const plainDateFromString = Temporal.PlainDate.from('2024-12-25');
console.log(plainDateFromString.toString()); // Output: 2024-12-25
دسترسی به اجزای تاریخ:
const year = plainDate.year; // 2024
const month = plainDate.month; // 10
const day = plainDate.day; // 26
const dayOfWeek = plainDate.dayOfWeek; // Day of the week (1-7, Monday-Sunday)
const dayOfYear = plainDate.dayOfYear; // Day of the year (1-366)
const daysInMonth = plainDate.daysInMonth; // Number of days in the month
const isLeapYear = plainDate.isLeapYear; // Boolean indicating if the year is a leap year
افزودن و کم کردن روزها:
const nextDay = plainDate.add({ days: 1 });
console.log(nextDay.toString()); // Output: 2024-10-27
const previousWeek = plainDate.subtract({ weeks: 1 });
console.log(previousWeek.toString()); // Output: 2024-10-19
مقایسه تاریخ ها:
const anotherDate = Temporal.PlainDate.from({ year: 2024, month: 11, day: 15 });
if (plainDate.equals(anotherDate)) {
console.log('Dates are equal');
} else if (plainDate.lessThan(anotherDate)) {
console.log('plainDate is earlier than anotherDate');
} else {
console.log('plainDate is later than anotherDate');
}
// Output: plainDate is earlier than anotherDate
کار با PlainTime
کلاس Temporal.PlainTime نشان دهنده زمان روز بدون هیچ گونه اطلاعات تاریخ یا منطقه زمانی است. برای نشان دادن ساعات کاری، زمان جلسات یا سایر رویدادهای مبتنی بر زمان مفید است.
ایجاد یک PlainTime:
const plainTime = Temporal.PlainTime.from({ hour: 14, minute: 30, second: 0 });
console.log(plainTime.toString()); // Output: 14:30:00
همچنین می توانید یک PlainTime از یک رشته در قالب ISO 8601 ایجاد کنید:
const plainTimeFromString = Temporal.PlainTime.from('09:00:00');
console.log(plainTimeFromString.toString()); // Output: 09:00:00
دسترسی به اجزای زمان:
const hour = plainTime.hour; // 14
const minute = plainTime.minute; // 30
const second = plainTime.second; // 0
const millisecond = plainTime.millisecond; // 0
const microsecond = plainTime.microsecond; // 0
const nanosecond = plainTime.nanosecond; // 0
افزودن و کم کردن زمان:
const laterTime = plainTime.add({ minutes: 15 });
console.log(laterTime.toString()); // Output: 14:45:00
const earlierTime = plainTime.subtract({ hours: 1 });
console.log(earlierTime.toString()); // Output: 13:30:00
مقایسه زمان ها:
const anotherTime = Temporal.PlainTime.from({ hour: 15, minute: 0, second: 0 });
if (plainTime.equals(anotherTime)) {
console.log('Times are equal');
} else if (plainTime.lessThan(anotherTime)) {
console.log('plainTime is earlier than anotherTime');
} else {
console.log('plainTime is later than anotherTime');
}
// Output: plainTime is earlier than anotherTime
کار با PlainDateTime
کلاس Temporal.PlainDateTime نشان دهنده تاریخ و زمان بدون هیچ گونه اطلاعات منطقه زمانی است. این کلاس عملکرد PlainDate و PlainTime را ترکیب می کند.
ایجاد یک PlainDateTime:
const plainDateTime = Temporal.PlainDateTime.from({ year: 2024, month: 10, day: 26, hour: 14, minute: 30, second: 0 });
console.log(plainDateTime.toString()); // Output: 2024-10-26T14:30:00
همچنین می توانید یک PlainDateTime از یک رشته در قالب ISO 8601 ایجاد کنید:
const plainDateTimeFromString = Temporal.PlainDateTime.from('2024-12-25T09:00:00');
console.log(plainDateTimeFromString.toString()); // Output: 2024-12-25T09:00:00
دسترسی به اجزای تاریخ و زمان:
const year = plainDateTime.year; // 2024
const month = plainDateTime.month; // 10
const day = plainDateTime.day; // 26
const hour = plainDateTime.hour; // 14
const minute = plainDateTime.minute; // 30
const second = plainDateTime.second; // 0
افزودن و کم کردن تاریخ ها و زمان ها:
const nextDayAndTime = plainDateTime.add({ days: 1, hours: 2 });
console.log(nextDayAndTime.toString()); // Output: 2024-10-27T16:30:00
const previousWeekAndTime = plainDateTime.subtract({ weeks: 1, minutes: 30 });
console.log(previousWeekAndTime.toString()); // Output: 2024-10-19T14:00:00
تبدیل به PlainDate و PlainTime:
const plainDateFromDateTime = plainDateTime.toPlainDate();
console.log(plainDateFromDateTime.toString()); // Output: 2024-10-26
const plainTimeFromDateTime = plainDateTime.toPlainTime();
console.log(plainTimeFromDateTime.toString()); // Output: 14:30:00
کار با ZonedDateTime
کلاس Temporal.ZonedDateTime نشان دهنده تاریخ و زمان با یک منطقه زمانی خاص است. این برای برنامه هایی که نیاز به مدیریت تاریخ ها و زمان ها در مکان های مختلف در سراسر جهان دارند بسیار مهم است. برخلاف شیء Date قدیمی، Temporal پشتیبانی داخلی از منطقه زمانی را فراهم می کند.
ایجاد یک ZonedDateTime:
const zonedDateTime = Temporal.ZonedDateTime.from({ year: 2024, month: 10, day: 26, hour: 14, minute: 30, second: 0, timeZone: 'America/Los_Angeles' });
console.log(zonedDateTime.toString()); // Output: 2024-10-26T14:30:00-07:00[America/Los_Angeles]
همچنین می توانید یک ZonedDateTime از یک Instant و یک منطقه زمانی ایجاد کنید:
const instant = Temporal.Instant.fromEpochSeconds(1666785000); // Example timestamp
const zonedDateTimeFromInstant = instant.toZonedDateTimeISO('Europe/London');
console.log(zonedDateTimeFromInstant.toString()); // Output will vary based on the actual instant but will reflect the date/time in Europe/London
دسترسی به اجزای تاریخ و زمان:
const year = zonedDateTime.year; // 2024
const month = zonedDateTime.month; // 10
const day = zonedDateTime.day; // 26
const hour = zonedDateTime.hour; // 14
const minute = zonedDateTime.minute; // 30
const second = zonedDateTime.second; // 0
const timeZone = zonedDateTime.timeZone; // Temporal.TimeZone object
تبدیل بین مناطق زمانی:
const newYorkDateTime = zonedDateTime.withTimeZone('America/New_York');
console.log(newYorkDateTime.toString()); // Output: 2024-10-26T17:30:00-04:00[America/New_York]
مدیریت زمان صرفه جویی در نور روز (DST):
Temporal به طور خودکار انتقال DST را مدیریت می کند. هنگام افزودن یا کم کردن زمان، DST را در نظر می گیرد و نتایج دقیقی را تضمین می کند. به عنوان مثال، جلسه ای را در نظر بگیرید که در طول انتقال DST در آلمان برنامه ریزی شده است:
const meetingStart = Temporal.ZonedDateTime.from({ year: 2024, month: 3, day: 31, hour: 2, minute: 30, timeZone: 'Europe/Berlin' });
const meetingEnd = meetingStart.add({ hours: 1 }); // Adding 1 hour
console.log(meetingEnd.toString()); // Output: 2024-03-31T03:30:00+02:00[Europe/Berlin]. Notice the offset changes due to DST
کار با Instant
کلاس Temporal.Instant نشان دهنده یک نقطه خاص در زمان است که بر حسب نانوثانیه از زمان epoch یونیکس اندازه گیری می شود. برای ذخیره و مقایسه لحظات دقیق در زمان مفید است.
ایجاد یک Instant:
const instant = Temporal.Instant.fromEpochSeconds(1666785000); // Example Unix timestamp in seconds
console.log(instant.toString()); // Output will be an ISO string representation of that instant
تبدیل به ZonedDateTime:
const zonedDateTimeFromInstant = instant.toZonedDateTimeISO('America/Los_Angeles');
console.log(zonedDateTimeFromInstant.toString()); // Output: Date and time in America/Los_Angeles corresponding to the instant
مقایسه Instant ها:
const anotherInstant = Temporal.Instant.fromEpochSeconds(1666790000);
if (instant.equals(anotherInstant)) {
console.log('Instants are equal');
} else if (instant.lessThan(anotherInstant)) {
console.log('instant is earlier than anotherInstant');
} else {
console.log('instant is later than anotherInstant');
}
// Output: instant is earlier than anotherInstant
کار با Duration
کلاس Temporal.Duration نشان دهنده یک مدت زمان است، مانند ساعت، دقیقه یا ثانیه. برای محاسبه تفاوت بین دو تاریخ یا زمان مفید است.
ایجاد یک Duration:
const duration = Temporal.Duration.from({ hours: 2, minutes: 30 });
console.log(duration.toString()); // Output: PT2H30M
محاسبه تفاوت بین تاریخ ها/زمان ها:
const startDate = Temporal.PlainDateTime.from({ year: 2024, month: 1, day: 1, hour: 0, minute: 0, second: 0 });
const endDate = Temporal.PlainDateTime.from({ year: 2024, month: 1, day: 3, hour: 12, minute: 30, second: 0 });
const difference = endDate.since(startDate);
console.log(difference.toString()); // Output: P2DT12H30M
// Accessing the components of the duration
console.log(difference.days); // 2
console.log(difference.hours); // 12
console.log(difference.minutes); // 30
افزودن Duration به تاریخ ها/زمان ها:
const newDate = startDate.add(duration);
console.log(newDate.toString()); // Output: 2024-01-03T02:30:00
کار با تقویم ها
Temporal API از سیستم های تقویم مختلف فراتر از تقویم میلادی پشتیبانی می کند. در حالی که هنوز به طور کامل در همه polyfill ها و موتورها پیاده سازی نشده است، هدف این است که به برنامه ها اجازه دهد تاریخ ها را در تقویم های خاص فرهنگ های مختلف مدیریت کنند. به عنوان مثال، برای استفاده از تقویم ژاپنی (به طور فرضی، از آنجا که پیاده سازی هنوز در حال تحول است):
// This is a conceptual example as calendar support is still under development
// const japaneseDate = Temporal.PlainDate.from({ year: 2024, month: 10, day: 26, calendar: 'japanese' });
// console.log(japaneseDate.toString()); // Expected: Output formatted according to the Japanese calendar
توجه: پشتیبانی از تقویم یک ویژگی در حال تکامل Temporal API است و عملکرد کامل هنوز به طور جهانی در دسترس نیست.
مثال ها و موارد استفاده عملی
Temporal API طیف گسترده ای از امکانات را برای مدیریت تاریخ ها و زمان ها در جاوا اسکریپت ارائه می دهد. در اینجا چند نمونه عملی و موارد استفاده آورده شده است:
- برنامه ریزی قرار ملاقات ها: یک برنامه زمان بندی ایجاد کنید که به کاربران امکان می دهد قرار ملاقات ها را در منطقه زمانی محلی خود رزرو کنند. Temporal.ZonedDateTime تبدیل بین مناطق زمانی و مدیریت انتقال DST را آسان می کند. برای یک کلینیک در برلین که قرار ملاقات ها را به صورت جهانی برنامه ریزی می کند:
- محاسبه سن: سن یک کاربر را بر اساس تاریخ تولد او تعیین کنید. PlainDate به شما امکان می دهد تاریخ تولد را بدون هیچ گونه اطلاعات منطقه زمانی نشان دهید.
- نمایش تاریخ ها و زمان ها در قالب های مختلف: تاریخ ها و زمان ها را مطابق با منطقه کاربر قالب بندی کنید. در حالی که ویژگی های بین المللی سازی (Intl) جدا هستند، اشیاء Temporal را می توان به راحتی با استفاده از
toLocaleString()یا روش های مشابه هنگام ترکیب با ویژگی های Intl API قالب بندی کرد. - پیگیری مدت زمان رویداد: مدت زمان یک رویداد را محاسبه کرده و آن را در یک قالب قابل خواندن توسط انسان نمایش دهید. Duration به شما امکان می دهد تفاوت زمانی بین دو تاریخ یا زمان را نشان دهید.
const appointmentTimeBerlin = Temporal.ZonedDateTime.from({ year: 2024, month: 11, day: 5, hour: 10, minute: 0, timeZone: 'Europe/Berlin' });
const appointmentTimeLA = appointmentTimeBerlin.withTimeZone('America/Los_Angeles');
console.log(`Appointment Time in Berlin: ${appointmentTimeBerlin.toString()}`);
console.log(`Appointment Time in Los Angeles: ${appointmentTimeLA.toString()}`);
const birthDate = Temporal.PlainDate.from({ year: 1990, month: 5, day: 15 });
const today = Temporal.Now.plainDateISO();
const age = today.year - birthDate.year - (today.month < birthDate.month || (today.month === birthDate.month && today.day < birthDate.day) ? 1 : 0);
console.log(`Age: ${age}`);
const zonedDateTimeNow = Temporal.Now.zonedDateTimeISO('en-GB');
console.log(zonedDateTimeNow.toLocaleString('en-GB'));
console.log(zonedDateTimeNow.toLocaleString('de-DE'));
const eventStart = Temporal.Instant.fromEpochSeconds(1700000000); // Example start timestamp
const eventEnd = Temporal.Instant.fromEpochSeconds(1700005000); // Example end timestamp
const durationOfEvent = eventEnd.since(eventStart);
console.log(`Event duration: ${durationOfEvent.minutes} minutes`);
بهترین شیوه ها برای استفاده از Temporal API
در اینجا چند بهترین شیوه برای به خاطر سپردن هنگام استفاده از Temporal API وجود دارد:
- از تغییرناپذیری استفاده کنید: تغییرناپذیری اشیاء Temporal را بپذیرید. از تغییر مستقیم اشیاء خودداری کنید. در عوض، اشیاء جدید را با استفاده از روش هایی مانند
add،subtractوwithایجاد کنید. - مناطق زمانی را با دقت مدیریت کنید: هنگام کار با تاریخ ها و زمان ها، به مناطق زمانی توجه داشته باشید. هنگام نیاز به نمایش تاریخ ها و زمان ها در یک منطقه زمانی خاص، از
ZonedDateTimeاستفاده کنید. - از نام های متغیر واضح استفاده کنید: از نام های متغیر توصیفی استفاده کنید که به وضوح نوع شیء Temporal مورد استفاده را نشان می دهند (به عنوان مثال،
plainDate،zonedDateTime،duration). - Polyfill ها را در نظر بگیرید: از آنجا که Temporal هنوز نسبتاً جدید است، با استفاده از یک کتابخانه polyfill در صورت نیاز، از پشتیبانی کافی اطمینان حاصل کنید.
- ورودی را اعتبارسنجی کنید: همیشه ورودی کاربر را اعتبارسنجی کنید تا اطمینان حاصل شود که تاریخ ها و زمان ها در قالب صحیح هستند.
انتقال از Date قدیمی
انتقال از شیء Date قدیمی می تواند یک فرآیند تدریجی باشد. این استراتژی ها را در نظر بگیرید:
- پذیرش افزایشی: با استفاده از Temporal در کد جدید شروع کنید و در عین حال
Dateرا در قسمت های موجود برنامه خود حفظ کنید. - توابع Wrapper: توابع wrapper ایجاد کنید که بین اشیاء
Dateو Temporal تبدیل می شوند تا قابلیت همکاری در طول انتقال را تسهیل کنند. - آزمایش کامل: مهاجرت را به طور گسترده آزمایش کنید تا اطمینان حاصل شود که تمام محاسبات تاریخ و زمان دقیق هستند.
Temporal API در مقابل Moment.js
Moment.js یک کتابخانه محبوب برای دستکاری تاریخ و زمان در جاوا اسکریپت بود، اما اکنون یک پروژه قدیمی در نظر گرفته می شود و در حالت نگهداری است. Temporal API یک راه حل مدرن تر و استانداردتر ارائه می دهد که بسیاری از کاستی های Moment.js را برطرف می کند. Moment.js قابل تغییر است و از منطقه زمانی بومی پشتیبانی نمی کند. Temporal API غیرقابل تغییر است و از منطقه زمانی بومی پشتیبانی می کند.
نتیجه گیری
JavaScript Temporal API نشان دهنده یک پیشرفت قابل توجه نسبت به شیء Date قدیمی است. تغییرناپذیری، API واضح، پشتیبانی از منطقه زمانی و پشتیبانی از تقویم آن را به ابزاری قدرتمند برای مدیریت تاریخ ها و زمان ها در برنامه های کاربردی مدرن جاوا اسکریپت تبدیل کرده است. در حالی که پذیرش هنوز در حال رشد است، استفاده از یک polyfill به شما امکان می دهد تا امروز از مزایای آن استفاده کنید. از آنجا که API به طور گسترده تری پشتیبانی می شود، انتظار می رود که به روش استاندارد برای کار با تاریخ ها و زمان ها در جاوا اسکریپت تبدیل شود.
Temporal API را بپذیرید و راهی کارآمدتر و قابل اعتمادتر برای مدیریت تاریخ ها و زمان ها در پروژه های خود را باز کنید و اطمینان حاصل کنید که برنامه شما مناطق زمانی جهانی و محاسبات را به طور دقیق مدیریت می کند.